<TeXmacs|1.99.16>

<project|rehash.tm>

<style|tmmanual>

<\body>
  <section|Hash manipulation>

  <include|scheme-hash-api.tm>

  <section|Query results>

  This API is implemented in the module <scm|(rehash)>.

  <todo|Perhaps this should be in a module <scm|(rehash query-result)>>

  <\explain>
    <scm|(query-result? <scm-arg|query-result>)><explain-synopsis|Test if
    object is a query result >
  <|explain>
    Check if <var|query-result> is a query result.

    <todo|export>
  </explain>

  <\explain>
    <scm|(from-dht? <scm-arg|query-result>)><explain-synopsis|Test if result
    came from DHT >
  <|explain>
    Check if <var|query-result> was found via the DHT.

    <todo|export>
  </explain>

  <\explain>
    <scm|(from-datastore? <scm-arg|query-result>)><explain-synopsis|Test if
    result came from datastore >
  <|explain>
    Check if <var|query-result> was found in the datastore.

    <todo|export>
  </explain>

  <\explain>
    <scm|(query-result-found-hash <scm-arg|query-result>)><explain-synopsis|Output
    hash>
  <|explain>
    Return the output hash found.

    <todo|export>
  </explain>

  <\explain>
    <scm|(query-result-expires <scm-arg|query-result>)><explain-synopsis|Expiration
    time>
  <|explain>
    When will this mapping expire? See Definitions in Section
    <reference|fibers-api-sec>.

    <todo|export>
  </explain>

  <section|Fibers API to Rehash><label|fibers-api-sec>

  This API is implemented in the module <code*|(rehash operations)>.

  <paragraph|Predicates> All predicates return return either <scm|#t> or
  <scm|#f>.

  <\explain>
    <scm|(rehash? <scm-arg|rehash>)><explain-synopsis|Test if object is a
    rehash handle >
  <|explain>
    Check if <var|rehash> is a handle to a rehash service.
  </explain>

  <\explain>
    <scm|(query? <scm-arg|query>)><explain-synopsis|Test if object is a query
    handle >
  <|explain>
    Check if <var|query> is a handle to a hash mapping search.
  </explain>

  <\explain>
    <scm|(store? <scm-arg|store>)><explain-synopsis|Test if object is a store
    handle >
  <|explain>
    Check if <var|store> is a handle to a hash mapping insertion.
  </explain>

  <paragraph|Definitions><label|fibers-definitions>

  <\description>
    <item*|Anonymity level>Currently implemented, for now always pass
    <scm|0>. \ In the future, this will be a small positive exact integer
    (\<less\> <math|2<rsup|32>>) controlling an anonymity-latency trade-off.

    <item*|Expiration time>A positive exact integer of microseconds since the
    epoch (must be \<less\> <math|2<rsup|64>> currently), indicating which
    blocks may be removed from the datastore when out of space. (See GNUnet
    documentation.)

    <item*|Content priority>When the datastore is full, the decision on which
    entry to remove first/last when out of space will be based upon the
    content priority of the blocks in the datastore (See GNUnet
    documentation). This is a positive exact integer, \<less\>
    <math|2<rsup|32>>.

    <item*|Replication level>How often should rehash attempt to migrate this
    block to other peers? This is a positive exact integer \<less\>
    <math|2<rsup|32>>. (See GNUnet documentation for more details)
    <todo|Content pushing is currently unimplemented.>
  </description>

  <paragraph|Making requests>

  <\explain>
    <scm|(connect-rehash <scm-arg|configuration>)><explain-synopsis|Connect
    to the rehash service >
  <|explain>
    Connect to the rehash service, using <var|configuration> as configuration
    handle. This is an asynchronuous operation, and can schedule work in
    GNUnet context.
  </explain>

  <\explain>
    <scm|(start-query! <scm-arg|rehash> #:input #:output-type
    #:anonymity-level=#f #:options=#f)><explain-synopsis|Search for a hash
    mapping >
  <|explain>
    Let <var|rehash> search for a hash of type <var|output-type>
    corresponding to the hash <var|input>. This is an asynchronuous
    operation. A query may be started after the rehash handle is closed,
    though this is of little use. A <scm|query?> handle is returned that can
    be used to wait for results and abort the query.

    <var|anonymity-level> See Definitions.

    <var|options> is currently unimplemented, for now always pass <scm|0>.
  </explain>

  <\explain>
    <scm|(store-mapping! <scm-arg|rehash> <scm-arg|input> <scm-arg|output>
    #:expiration-time=#f #:anonymity-level=#f #:content-priority=#f
    #:replication-level=#f)><explain-synopsis|Insert a hash mapping >
  <|explain>
    Insert the hash mapping <math|<around*|(|<text|<var|input>>,<text|<var|output>>|)>>
    into rehash. (Both the datastore and DHT, anonymity permitting), to be
    shared with other peers. If a mapping from <var|input> to a hash of the
    same type as <var|output> already exists, the old entry is considered
    faulty and is replaced with the new mapping. This is an asynchronuous
    operation.

    A store may be started after the rehash handle is closed, though such a
    store would never complete. A <scm|store?> handle is returned that can be
    used to abort the insertion, and wait for its completion.

    <todo|Content pushing and invalidation is not yet implemented. The exact
    semantics may change in the future.>

    <var|expiration-time>, <var|anonymity-level>, <var|content-priority>,
    <var|replication-level> See Definitions.
  </explain>

  <paragraph|Waiting on results>

  <\explain>
    <scm|(wait-for-store-done <scm-arg|store>)><explain-synopsis|Wait until a
    mapping is inserted>
  <|explain>
    Wait until a hash mapping insertion <var|store> has been performed, or
    aborted. In the former case, return <scm|#t>. In the latter case, return
    <scm|#f>. This procedure prefers returning <scm|#t>.
  </explain>

  <\explain>
    <scm|(wait-for-store-done-operation <scm-arg|store>)><explain-synopsis|Operation
    for waiting until a hash mapping is inserted>
  <|explain>
    Make an operation, with zero return values, that waits until the store
    <var|store> has completed. This operation will never return if the
    insertion is aborted before the hash mapping is inserted.
  </explain>

  <\explain>
    <scm|(query-result-operation <scm-arg|query>)><explain-synopsis|Operation
    for waiting until an output hash is found>
  <|explain>
    Make an operation with as return value the next <scm|query-result?>. This
    operation will never return if the query is aborted before a hash is
    found. The comment about finding more output hashes in the documentation
    of <scm|query-next-result> also applies here.
  </explain>

  <\explain>
    <scm|(query-next-result <scm-arg|query>)><explain-synopsis|Wait until an
    output hash is found>
  <|explain>
    Wait for query <var|query> to find an output hash of the desired type,
    and return the corresponding <scm|query-result?>. If the query is aborted
    before a hash could be found, return <scm|#f> instead. This procedure can
    be called again to find more output hashes. It is not guaranteed that all
    found hashes will be different.
  </explain>

  <paragraph|Interrupting requests>

  <\explain>
    <scm|(disconnect-rehash <scm-arg|rehash>)><explain-synopsis|Disconnect
    from the rehash service>
  <|explain>
    Disconnect from the rehash service <var|rehash>. This procedure is
    idempotent. Disconnecting will result in abortion of all associated
    queries and stores. This is an asynchronuous operation.
  </explain>

  <\explain>
    <scm|(abort-query! <scm-arg|query>)><explain-synopsis|Stop searching for
    a hash mapping>
  <|explain>
    Abort a query <var|query>. This procedure is idempotent. This is an
    asynchronuous operation. Due to concurrency issues, it is possible a
    result will still be found, but only in the near future.
  </explain>

  <\explain>
    <scm|(abort-store! <scm-arg|store>)><explain-synopsis|Stop trying to
    insert a hash mapping>
  <|explain>
    Abort a hash insertion <var|store>. This procedure is idempotent. This is
    an asynchronuous operation. Due to concurrency issues, it is possible the
    store will still complete, but only in the near future.
  </explain>

  <paragraph|Waiting on interrupts>

  <\explain>
    <scm|(wait-for-closed-operation <scm-arg|rehash>)><explain-synopsis|Operation
    waiting until <var|rehash> is closed>
  <|explain>
    Make an operation, with zero return values, that waits until the
    connection <var|rehash> to the rehash service is closed.
  </explain>

  <\explain>
    <scm|(wait-for-closed <scm-arg|rehash>)><explain-synopsis|Wait until
    <var|rehash> is closed>
  <|explain>
    Wait until the connection <var|rehash> to the rehash service is closed.
  </explain>

  <\explain>
    <scm|(wait-for-query-aborted-operation
    <scm-arg|query>)><explain-synopsis|Operation waiting until a query is
    aborted>
  <|explain>
    Make an operation, with zero return values, that waits until the query
    <var|query> is aborted.
  </explain>

  <\explain>
    <scm|(wait-for-query-aborted <scm-arg|query>)><explain-synopsis|Wait
    until a query is aborted>
  <|explain>
    Wait until the query <var|query> is aborted.
  </explain>

  <\explain>
    <scm|(wait-for-store-aborted-operation
    <scm-arg|store>)><explain-synopsis|Operation waiting until an insertion
    is aborted>
  <|explain>
    Make an operation, with zero return values, that waits until the hash
    mapping insertion <var|store> is aborted.
  </explain>
</body>

<\initial>
  <\collection>
    <associate|chapter-nr|5>
    <associate|page-first|15>
    <associate|save-aux|false>
    <associate|section-nr|0>
    <associate|subsection-nr|4>
  </collection>
</initial>